from pathlib import Path
import ctypes
from ctypes import wintypes


class WindowsPathManager:
    """Windows系统路径管理工具类。

    该类提供静态方法，用于获取Windows系统中各类标准目录的路径，
    包括桌面、文档、音乐、视频等文件夹。通过结合pathlib和Windows API调用，
    确保在不同系统配置下的兼容性。
    """

    @staticmethod
    def get_desktop_path() -> str:
        """获取当前用户的桌面文件夹路径。

        Returns:
            str: 桌面文件夹的绝对路径（例如："C:\\Users\\用户名\\Desktop"）
        """
        return str(Path.home() / "Desktop")

    @staticmethod
    def get_user_path() -> str:
        """获取当前用户的主目录路径。

        Returns:
            str: 用户主目录的绝对路径（例如："C:\\Users\\用户名"）
        """
        return str(Path.home())

    @staticmethod
    def get_documents_path() -> str:
        """获取当前用户的「我的文档」文件夹路径。

        使用Windows API的SHGetFolderPathW函数，配合CSIDL_PERSONAL（5）标识，
        确保即使用户自定义文件夹位置时仍能正确获取路径。

        Returns:
            str: 「我的文档」文件夹的绝对路径
        """
        return WindowsPathManager._get_special_folder_path(5)

    @staticmethod
    def get_music_path() -> str:
        """获取当前用户的「我的音乐」文件夹路径。

        使用Windows API的SHGetFolderPathW函数，配合CSIDL_MYMUSIC（13）标识。

        Returns:
            str: 「我的音乐」文件夹的绝对路径
        """
        return WindowsPathManager._get_special_folder_path(13)

    @staticmethod
    def get_videos_path() -> str:
        """获取当前用户的「我的视频」文件夹路径。

        使用Windows API的SHGetFolderPathW函数，配合CSIDL_MYVIDEO（14）标识。

        Returns:
            str: 「我的视频」文件夹的绝对路径
        """
        return WindowsPathManager._get_special_folder_path(14)

    @staticmethod
    def get_pictures_path() -> str:
        """获取当前用户的「我的图片」文件夹路径。

        使用Windows API的SHGetFolderPathW函数，配合CSIDL_MYPICTURES（39）标识。

        Returns:
            str: 「我的图片」文件夹的绝对路径
        """
        return WindowsPathManager._get_special_folder_path(39)

    @staticmethod
    def get_favorites_path() -> str:
        """获取当前用户的收藏夹路径。

        使用Windows API的SHGetFolderPathW函数，配合CSIDL_FAVORITES（6）标识。

        Returns:
            str: 收藏夹文件夹的绝对路径
        """
        return WindowsPathManager._get_special_folder_path(6)

    @staticmethod
    def get_searches_path() -> str:
        """获取当前用户的搜索文件夹路径。

        使用Windows API的SHGetFolderPathW函数，配合CSIDL_SEARCH（32）标识。

        Returns:
            str: 搜索文件夹的绝对路径
        """
        return WindowsPathManager._get_special_folder_path(32)

    @staticmethod
    def _get_special_folder_path(csidl: int) -> str:
        """通过Windows API获取特殊文件夹路径的内部工具方法。

        调用SHGetFolderPathW函数，根据传入的CSIDL标识获取对应文件夹路径。

        参数:
            csidl: 特殊文件夹的CSIDL标识（Windows系统定义的常量）

        Returns:
            str: 特殊文件夹的绝对路径
        """
        # 创建Unicode存储路径的缓冲区
        buf = ctypes.create_unicode_buffer(wintypes.MAX_PATH)
        
        # 调用Windows API获取路径
        # 参数说明：hwnd=0（无父窗口）, csidl=文件夹标识, hToken=0（当前用户）,
        #          dwFlags=0（默认设置）, pszPath=输出缓冲区
        ctypes.windll.shell32.SHGetFolderPathW(None, csidl, None, 0, buf)
        
        return buf.value